This PR addresses the question about select_related support by adding comprehensive documentation explaining why it's not supported and providing practical alternatives.

Background

The issue asked whether select_related would be considered out of scope for django-tree-queries. As discussed in the comments, select_related support is intentionally not implemented due to the complexity of combining recursive Common Table Expressions (CTEs) with Django's join mechanisms, which could compromise the library's stability across Django versions.

Changes

Added a new "Working with Related Models and Constraints" section to the README that includes:

Clear Explanation of Limitations

• Why select_related() is not supported with tree queries
• How recursive CTEs conflict with Django's join optimization
• Other related limitations (complex annotations, direct UPDATE queries, etc.)

Comprehensive Workarounds with Examples

Using prefetch_related() instead:

# Works great with tree queries
tree_nodes = Model.objects.with_tree_fields().prefetch_related('referencemodel_set')

Using Django's Prefetch() for fine control:

tree_nodes = Model.objects.with_tree_fields().prefetch_related(
    Prefetch('referencemodel_set',
             queryset=ReferenceModel.objects.select_related('other_field'))
)

Tree queries in filter conditions (proven pattern from test suite):

references = ReferenceModel.objects.filter(
    tree_field__in=some_node.descendants(include_self=True)
)

Design Philosophy Context

Explains why these constraints exist and how they maintain django-tree-queries' core strengths:

• Stability: Works consistently across Django 3.2 to 5.x
• Simplicity: Fewer features mean fewer bugs and edge cases
• Performance: CTE-based approach optimized for tree operations
• Reliability: Avoiding complex query combinations keeps behavior predictable

Validation

All documented patterns are validated against existing test cases, particularly the test_reference() method which extensively uses the recommended tree_field__in=tree_node.descendants() pattern. The examples follow established Django ORM best practices and provide clear, maintainable alternatives to select_related().

This documentation-first approach respects the maintainer's decision about scope while empowering developers with proven techniques for working efficiently with both tree models and related models.

Fixes #18.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.